I believe most beginners when they start writing programs, are more focused on the actual code than the way they have written it. But any programmer that has aspirations to writing a 10,000 to 20,000 line monster program should develop a writing style that will make those programs readable by others and certainly the programmer themselves after months or years go by.
The dictionary has one definition of style as "A customary manner of presenting printed material, including usage, punctuation, spelling, typography, and arrangement". It's not my intention to convey that my writing style, which I'll give examples of here, is "correct" or "the only way". But it is my style that I have developed after more than 30 years of casual programming and "it works for me". My real intent is to get beginners to think about the way they have arranged their programs, assigned variables, chosen handles, used indentation etc.
I would think that good arrangement is probably crucial in being able to follow the flow of the program. I would recommend the reader looks at Event Driven Concepts Part 1 & 2 - NL102 & NL104 by Brad Moore and Development of Large Programs with LB - NL46 by Herman to get an idea of how large programs should be constructed. With these articles in mind, I would like to define the program arrangement a little further.
Most large programs will usually have arrays, global variables, an initialization file, a Main Window with menu items, many windows to perform operations as well as subroutines and functions. My definition of a window in this discussion is a section of program that will usually contain a window and performs one basic operation in the program. I usually arrange the parts of the program in the following order.
The whole point of my arrangement is so that I know about where things are in the program. The way Liberty Basic uses the Jump To pane, some consistent type of arrangement makes it very easy to find things.
Each person is going to have their way of assigning variables. The problem is, there are usually so many variables used in a program, that the beginner gets confused about which one he has already used and how they were typed in the first place. So the programmer should make up a set of rules for themselves, even resorting to writing them down if necessary. Here are the rules I have for myself, which I always follow. Believe that and I have a TRS-80 to sell you.
I always type commands such as open, print etc in lower case. I just find it easier to read for me and quicker than typing Open, Print etc. If a variable is going to be used more as place holder than something I need to refer to later within the window I would write program lines that look like this:
for x=1 to y a=instr(a$,"b")
I might use 'a' again for a different reason 5 lines further on.
If I need a variable that will be used in several places within a window that I need to keep track of, they need to be more descriptive and I will usually write it as:
for x=1 to numbercolors a=instr(color$,"a")
If I have a variable that will be used between many windows, I would write is as NumberColors=999. Global variables as defined in LB4 are written as ERRORFLAG.
Like variables which are global to the program, I find array names are easier remembered if I type them like NameArray$( or ColorArray$(. Sometimes when an array is only for a list box, I might use the name NameList$( or ColorList$(. Since the array name will always be followed by a '(', it's easy to distinguish between my global variable and an array name.
Again I have a set of rules I try to follow when assigning branch labels.
If a branch label is called from a Main Menu item or is a gosub label it will always be descriptive and written [SortNames] or [Add NamesToFile]. If I have a branch label within window operation, they will usually contain the window handle name with a descriptor and might look like this:
[nameaddClick1] 'Add the name to the file
or
[nameaddClick2] 'Close window
Note that I also include a remark that will describe what this branch is for. Again, the way the Liberty Basic Jump To works, its easy to see in the branch label pane what a branch is for before you click on it to jump there.
If I have to have a 'goto' branch label within a window, it would look like [nameadd1] or [nameadd2].
Again, because the Jump To pane displays all branch labels, I might have an extra branch label somewhere between the end of the GUI definition and the first wait statement that does nothing except make it easy for me to find the start of the window operation. This might look like [nameaddstart].
Handle names for a window and controls are always type in lower case and describe what the window is for. They might look like #nameadd or #namechg. Being a lazy sort, I will type handle extensions for controls such as #nameadd.tb1, #nameadd.st1, #nameadd.lb1, #nameadd.cb1, #nameadd.b1, #nameadd.bmp1, #nameadd.rb1 and #nameadd.cob1 for a combo box. Some folks will use a descriptive extension for a control such as #nameadd.help. In some cases I do myself but I usually prefer to use to use the previous mentioned extensions as almost anyone can tell at a glance from the extension, what kind of control it is for.
Don't ask me how I got started doing this, but file handles were always #1 or #2. That's probably a hold over from GW Basic or older. I persisted in that naming until recently. One day I had a section of code that was a couple of hundred lines long and had several files opened at the same time. Depending on a bunch of different conditions, some of the files were closed at different times and then opened again later. I got so confused; I never knew which were supposed to be opened and which were closed. I now label all file handles very descriptively such as #EntryFile or #ColorFile or #TempText. Again the uppercase triggers that this is a file handle and not a window handle so when I see 'close #nameadd' I know it's a window being closed and not a file.
I believe indentation is one of the more important parts of programming style. It will go a long way in helping to find those annoying errors like a missing next or end if or end select that keep a program from running. I do a lot of indentation and a section of code might look like this:
[manage colorclick2] 'find number of colors and do something flag=0 'flag=0 number of colors > 50 for x=1 to numbercolors if numbercolors <50 then flag=1 'number of colors <50 more code more code select case a case 1 more code more code case 2 more code case else more code end select else more code more code for y=1 to lastcolor if lastcolor=ColorArray(y) then more code end if more code next y end if next x wait
If I have a bunch of nested loops, I might even type the last line as 'next x" so I know which 'for' this 'next' goes with.
My son makes his living as a programmer for IBM and writes in C++ and Java. Because his group may write different sections of a huge finished program, it becomes very important to remark almost every line of code. That's not so important for the individual programmer unless they are writing open source code. I can tell you from personal experience, even though you know exactly what a section of code does now, in two months, when someone finds a bug in your program or you need to make a change, that complicated section of code has becomes so un-readable to you that you almost feel like writing it over. But you can't because you can't be sure that in re writing it, you won't pop the balloon out somewhere else. As I mentioned earlier, I place remarks behind almost every branch label so I know what the section of code does and it helps to find the correct section in the Jump To pane. I also label what a flag is for and what the conditions are for the flag. When I finish a program, I go through it section by section. If it is immediately apparent what the section does, I may not place any remarks with it. Often, I have to stop and think "What did I do here?" Then I know, if I can't figure it out right now, what will it look to me like in six months or six years? So, write as many remarks as you think you will need and it still won't be enough.
Alyce Watson wrote an article on White Space or blank lines. Blank lines that provide white space between sections of code are also important to making a program readable. I put two blank lines between the end of one window operation and the branch label for the next operation. Within a window operation, I'll put only one blank line between the end of one section and the branch label for the next section. If I have a complicated section I may put a blank line between different parts. For example, I may have under a single branch label, a section that massages data and saves it to a file. Then under the same branch label, I need to clear a bunch of variables before I 'return' or 'wait'. I'll usually put a blank line between the two sections and may even put a remark as well.
Code that I have copied and pasted from another source is left alone. Whatever style the original programmer used remains intact. In fact, recently I made a new rule for myself. I have copied and pasted so much from a variety of sources, I no longer remember where each came from. Even though no one might ever see the source code of the program, I now place a few remarks as to where the code came from. I have found that I often want to go and look at the original source for more information or a particular feature. Now I know where to look.
Now that I have told you more than you ever wanted to know about writing style, you might look at other's programs with a different eye. Take a look at the way each individual writes. After a while, you can almost look at code and say, Alyce or Dennis or Tom wrote this. Don't take what I have written as gospel. (Editor, can I say gospel here?) [Affirmative.--Ed] Whatever style you choose to use, try to be consistent. That's really the key to writing programs in a customary manner that you and others can read and understand.